This is a comment left during a code review.
Path: Dockerfile
Line: 61-62

Comment:
**Build-arg `USER_UID`/`USER_GID` not propagated to runtime `ENV`**

`ARG` values are scoped to the stage they are declared in. `ARG USER_UID=1000` / `ARG USER_GID=1000` are declared in the `base` stage, but the `production` stage never re-declares them. As a result, the `ENV` block hardcodes the literal `1000` rather than forwarding the build-arg value.

**Concrete failure scenario:** `docker build --build-arg USER_UID=1001 -t paperclip-test .`

1. `base` stage: `usermod -u 1001 node` runs correctly — `node` user is UID 1001 in the image layer.
2. `production` stage: `ENV USER_UID=1000` — runtime default is still **1000**.
3. Container start: entrypoint reads `PUID=1000`, sees `id -u node` is 1001, and runs `usermod -o -u 1000 node` — **undoing the build-time baking entirely**.

The fix is to re-declare the ARGs in the `production` stage and use them in the `ENV` block:

```
ARG USER_UID=1000
ARG USER_GID=1000

ENV NODE_ENV=production \
  ...
  USER_UID=${USER_UID} \
  USER_GID=${USER_GID} \
  ...
```

How can I resolve this? If you propose a fix, please make it concise.

This is a comment left during a code review.
Path: docker-entrypoint.sh
Line: 20

Comment:
**`chown -R` runs unconditionally on every container start**

`chown -R node:node /paperclip` is not guarded behind the UID/GID-change branches — it executes on **every startup**, including the common default case where no remapping is needed. This contradicts the PR description's claim that "the entrypoint detects no UID/GID change and immediately exec-s the server with zero overhead."

For an AI agent orchestration platform, `/paperclip` accumulates persistent state (logs, databases, agent artefacts). A recursive `chown` over a large directory tree on every container restart introduces measurable startup latency that will grow over time.

The standard remedy is to move `chown` inside the branches so it only runs when a remap actually happened:

```sh
changed=0

if [ "$(id -u node)" -ne "$PUID" ]; then
    echo "Updating node UID to $PUID"
    usermod -o -u "$PUID" node
    changed=1
fi

if [ "$(id -g node)" -ne "$PGID" ]; then
    echo "Updating node GID to $PGID"
    groupmod -o -g "$PGID" node
    changed=1
fi

if [ "$changed" = "1" ]; then
    chown -R node:node /paperclip
fi
```

How can I resolve this? If you propose a fix, please make it concise.

This is a comment left during a code review.
Path: docker-entrypoint.sh
Line: 17-21

Comment:
**GID remapping is silently broken**

`groupmod -o -g "$PGID" node` updates the GID record in `/etc/group` but does **not** update the user's primary GID field stored in `/etc/passwd`. When `exec gosu node "$@"` runs, `gosu` calls `getpwnam("node")` which reads the primary GID from `/etc/passwd` — still the original value. The process therefore always starts with the old GID, regardless of what `USER_GID` is set to.

Concrete consequence: with `USER_GID=1001`:
1. `groupmod -o -g 1001 node` → `/etc/group` now says `node:x:1001:`
2. `chown -R node:node /paperclip` → sets `/paperclip` gid to 1001 (resolving via `/etc/group`)
3. `exec gosu node` → reads `/etc/passwd`, primary gid = 1000 (unchanged) → process runs as gid=1000
4. New files created by the server inside `/paperclip` are owned by gid=1000, not the intended 1001 — the host user with gid=1001 has no group write access to them

The same issue affects the build-time `groupmod` step in the `Dockerfile` (line 11).

The fix is to call `usermod -g "$PGID" node` after `groupmod`, which updates the primary GID entry in `/etc/passwd`:

```suggestion
if [ "$(id -g node)" -ne "$PGID" ]; then
    echo "Updating node GID to $PGID"
    groupmod -o -g "$PGID" node
    usermod -g "$PGID" node
    changed=1
fi
```

And in the `Dockerfile` build-time block:
```dockerfile
RUN usermod -u $USER_UID --non-unique node \
  && groupmod -g $USER_GID --non-unique node \
  && usermod -g $USER_GID node
```

How can I resolve this? If you propose a fix, please make it concise.